---
title: azure-openai
---

<Note>
  If you are using the new Microsoft Foundry (new) portal, please use: [`microsoft-foundry`](microsoft-foundry) instead.
</Note>

For `azure-openai`, we provide a client that can be used to interact with the OpenAI API hosted on Azure using the `/chat/completions` endpoint.

Example:
```baml BAML
client<llm> MyClient {
  provider azure-openai
  options {
    resource_name "my-resource-name"
    deployment_id "my-deployment-id"
    // Alternatively, you can use the base_url field
    // base_url "https://my-resource-name.openai.azure.com/openai/deployments/my-deployment-id"
    api_version "2024-02-01"
    api_key env.AZURE_OPENAI_API_KEY
  }
}
```

<Warning>
  `api_version` is required. Azure will return not found if the version is not specified.
</Warning>


The options are passed through directly to the API, barring a few. Here's a shorthand of the options:

## BAML-specific request `options`
These unique parameters (aka `options`) modify the API request sent to the provider.

You can use this to modify the azure api key, base url, and api version for example.


<ParamField
  path="api_key"
  type="string"
>
  Will be injected via the header `API-KEY`. **Default: `env.AZURE_OPENAI_API_KEY`**

  `API-KEY: $api_key`
</ParamField>

<ParamField
  path="base_url"
  type="string"
>
  The base URL for the API. **Default: `https://${resource_name}.openai.azure.com/openai/deployments/${deployment_id}`**

  May be used instead of `resource_name` and `deployment_id`.
</ParamField>

<ParamField
  path="deployment_id"
  type="string"
  required
>
  See the `base_url` field.
</ParamField>

<ParamField
  path="resource_name"
  type="string"
  required
>
  See the `base_url` field.
</ParamField>

<ParamField path="api_version" type="string" required>
  Will be passed via a query parameter `api-version`.
</ParamField>

<ParamField path="headers" type="object">
  Additional headers to send with the request.

Example:
```baml BAML
client<llm> MyClient {
  provider azure-openai
  options {
    resource_name "my-resource-name"
    deployment_id "my-deployment-id"
    api_version "2024-02-01"
    api_key env.AZURE_OPENAI_API_KEY
    headers {
      "X-My-Header" "my-value"
    }
  }
}
```
</ParamField>

<Markdown src="/snippets/role-selection.mdx" />

<Markdown src="/snippets/allowed-role-metadata-basic.mdx" />

<Markdown src="/snippets/supports-streaming.mdx" />

<Markdown src="/snippets/finish-reason.mdx" />

<Markdown src="/snippets/client-response-type.mdx" />

<Markdown src="/snippets/media-url-handler.mdx" />

## Provider request parameters
These are other `options` that are passed through to the provider, without modification by BAML. For example if the request has a `temperature` field, you can define it in the client here so every call has that set.

Consult the specific provider's documentation for more information.

<Warning>
  For reasoning models (like `o1` or `o1-mini`), you must use `max_completion_tokens` instead of `max_tokens`.
  Please set `max_tokens` to `null` in order to get this to work.

  See the [OpenAI API documentation](https://platform.openai.com/docs/api-reference/chat/create#chat-create-max_completion_tokens) and [OpenAI Reasoning Docs](https://platform.openai.com/docs/guides/reasoning#controlling-costs) for more details about token handling.

  Example:

  ```baml BAML
  client<llm> AzureO1 {
    provider azure-openai
    options {
      deployment_id "o1-mini"
      max_tokens null
    }
  }
  ```
</Warning>

<ParamField
   path="messages"
   type="DO NOT USE"
>
  BAML will auto construct this field for you from the prompt
</ParamField>
<ParamField
   path="stream"
   type="DO NOT USE"
>
  BAML will auto construct this field for you based on how you call the client in your code
</ParamField>

For all other options, see the [official Azure API documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#chat-completions).
